Examples where this is necessary include
A fairly common feature in applications is to allow you to define a C function that will get called whenever something nasty occurs. What we would like is for a Perl sub to be called instead.
Before you launch yourself head first into the rest of this document, it would be a good idea to have read the following two documents - the perlapi manpage and the perlguts manpage .
This stuff is easier to explain using examples. But first here are a few definitions anyway.
The key function is perl_call_sv . All the other functions make use of perl_call_sv to do what they do.
perl_call_sv takes two parameters, the first is an SV*. This allows you to
specify the Perl sub to be called either as a C string (which has first been
converted to an SV) or a reference to a
sub. Example 7, shows you how you can make use of perl_call_sv .
The second parameter, flags , is a general purpose option command.
This parameter is common to all the perl_call_* functions.
It is discussed in the next section.
The function, perl_call_pv , is similar as perl_call_sv except it
expects it's first parameter has to be a C char* which identifies the Perl
sub you want to call, e.g. perl_call_pv("fred", 0) .
The function perl_call_method expects its first argument to contain a
blessed reference to a class. Using that reference it looks up and calls methname
from that class. See example 9.
perl_call_argv calls the Perl sub specified by the subname parameter.
It also takes the usual flags parameter.
The final parameter, argv , consists of a
list of C strings to be sent to the Perl sub. See example 8.
All the functions return a number. This is a count of the number of items returned by the Perl sub on the stack.
As a general rule you should always check the return value from these functions. Even if you are only expecting a particular number of values to be returned from the Perl sub, there is nothing to stop someone from doing something unexpected - don't say you havn't been warned.
flags parameter in all the perl_call_* functions consists of any
combination of the symbols defined below, OR'ed together.
Whatever the Perl sub actually returns, we only want a scalar. If the perl sub does return a scalar, the return value from the perl_call_* function will be 1 or 0. If 1, then the value actually returned by the Perl sub will be contained on the top of the stack. If 0, then the sub has probably called die or you have used the G_DISCARD flag.
If the Perl sub returns a list, the perl_call_* function will still only return 1 or 0. If 1, then the number of elements in the list will be stored on top of the stack. The actual values of the list will not be accessable.
G_SCALAR is the default flag setting for all the functions.
The return code from the perl_call_* functions will indicate how many elements of the stack are used to store the array.
If you do not set this flag then you may need to explicitly get rid of temporary values. See example 3 for details.
@_ array
for the Perl sub.
A point worth noting is that if this flag is specified the Perl sub called can
still access an @_ array from a previous Perl sub.
This functionality can be illustrated with the perl code below
This will print
What has happened is that fred accesses the @_ array which belongs to joe .
Whenever control returns from the perl_call_* function you need to check the $@ variable as you would in a normal Perl script. See example 6 for details of how to do this.
Perl provides many macros to assist in accessing the Perl stack. These macros should always be used when interfacing to Perl internals. Hopefully this should make the code less vulnerable to changes made to Perl in the future.
Another point worth noting is that in the first series of examples I have only made use of the perl_call_pv function. This has only been done to ease you into the topic. Wherever possible, if the choice is between using perl_call_pv and perl_call_sv , I would always try to use perl_call_sv .
The code for these examples is stored in the file perlcall.tar . (Once this document settles down, all the example code will be available in the file).
and here is the C to call it
Simple, eh.
A few points to note about this example.
dSP and PUSHMARK(sp) for now. They will be discussed in the next
example.
$s ) and an integer ( $n ).
The sub will simply print the first $n characters of the string.
So the Perl sub would look like this
The C function required to call LeftString would look like this.
Here are a few notes on the C function call_LeftString .
dSP and ending
with the line PUTBACK .
dSP -
it declares and initialises a local copy of the Perl stack pointer.
All the other macros which will be used in this example require you to have used this macro.
If you are calling a Perl sub directly from an XSUB function, it is
not necessary to explicitly use the dSP macro - it will be declared for you.
PUSHMARK and PUTBACK macros.
The purpose of these two macros, in this context, is to automatically count
the number of parameters you are pushing. Then whenever Perl is creating
the @_ array for the sub, it knows how big to make it.
The PUSHMARK macro tells Perl to make a mental note of the current stack
pointer. Even if you aren't passing any parameters (like in Example 1) you must
still call the PUSHMARK macro before you can call any of
the perl_call_* functions - Perl still needs to know that there are
no parameters.
The PUTBACK macro sets the global copy of the stack pointer to be the
same as our local copy. If we didn't do this perl_call_pv wouldn't
know where the two parameters we pushed were - remember that up to now
all the stack pointer manipulation we have done is with our local copy,
not the global copy.
See the section XSUB's AND THE ARGUMENT STACK in the perlguts manpage for details on how the XPUSH macros work.
Here is a Perl sub, Adder , which takes 2 integer parameters and simply returns their sum.
As we are now concerned with the return value from Adder , the C function is now a bit more complex.
Points to note this time are
at the start of the function, and
at the end. The ENTER / SAVETMPS pair creates a boundary for any
temporaries we create.
This means that the temporaries we get rid of will be limited to those which
were created after these calls.
The FREETMPS / LEAVE pair will get rid of any values returned by the Perl
sub, plus it will also dump the mortal SV's we created.
Having ENTER / SAVETMPS at the beginning
of the code makes sure that no other mortals are destroyed.
SPAGAIN is to refresh the local copy of the
stack pointer. This is necessary because it is possible that the memory
allocated to the Perl stack has been re-allocated whilst in the perl_call_pv
call.
If you are making use of the Perl stack pointer in your code you must always refresh the your local copy using SPAGAIN whenever you make use of of the perl_call_* functions or any other Perl internal function.
Expecting a single value is not quite the same as knowing that there will be one. If someone modified Adder to return a list and we didn't check for that possibility and take appropriate action the Perl stack would end up in an inconsistant state. That is something you really don't want to ever happen.
POPi macro is used here to pop the return value from the stack. In this
case we wanted an integer, so POPi was used.
Here is the complete list of POP macros available, along with the types they return.
PUTBACK is used to leave the Perl stack in a consistant state
before exiting the function. This is
necessary because when we popped the return value from the stack with POPi it
only updated our local copy of the stack pointer. Remember, PUTBACK sets the
global stack pointer to be the same as our local copy.
Here is the Perl sub
and this is the C function
Notes
The Perl sub, Inc , below takes 2 parameters and increments each.
and here is a C function to call it.
To be able to access the two parameters that were pushed onto the stack
after they return from perl_call_pv it is necessary to make a note of
their addresses - thus the two variables sva and svb .
The reason this is necessary is that the area of the Perl stack which held them will very likely have been overwritten by something else by the time control returns from perl_call_pv .
and some C to call it
If call_Subtract is called thus
the following will be printed
Notes
is the equivalent of this bit of Perl
Consider the Perl code below
here is a snippet of XSUB which defines CallSub .
That is fine as far as it goes. The thing is, it only allows the Perl sub to be specified as a string. For perl 4 this was adequate, but Perl 5 allows references to subs and anonymous subs. This is where perl_call_sv is useful.
The code below for CallSub is identical to the previous time except that the
name parameter is now defined as an SV* and we use perl_call_sv instead of
perl_call_pv .
As we are using an SV to call fred the following can all be used
As you can see, perl_call_sv gives you greater flexibility in how you can specify the Perl sub.
and here is an example of perl_call_argv which will call PrintList .
Note that it is not necessary to call PUSHMARK in this instance. This is
because perl_call_argv will do it for you.
Consider the following Perl code
The method Display just prints out the first element of the list.
Here is a XSUB implementation of call_Display .
One of the trickiest problems to overcome when designing a callback interface is figuring out how to store the mapping between the C callback functions and the Perl equivalent.
Consider the following example.
Although I have only made use of the POP* macros to access values returned from Perl subs, it is also possible to bypass these macros and read the stack directly.
The code below is example 4 recoded to
Special thanks to the following people who assisted in the creation of the document.
Jeff Okamoto, Tim Bunce.